PYTHON-6054 Align span and log operation names with the OTel spec by blink1073 · Pull Request #3111 · mongodb/mongo-python-driver

blink1073 · 2026-10-08T22:27:52Z

Companion spec PR: DRIVERS-3625 (mongodb/specifications#1993)

Changes in this PR

Aligns db.operation.name reported on tracing spans with the operation names defined in the OpenTelemetry specification, and uses the same names in server selection logging (falling back to the command name for commands without a listed operation):

countDocuments, watch, renameCollection, collection-level bulkWrite, and both generic command helpers.

Also:

Resyncs the OpenTelemetry and server selection logging spec tests with the spec update.
Guards the client bulk_write span tests to servers with the bulkWrite command.
Sweeps the otel variant across all supported server versions.

Test Plan

Updated the otel span tests and resynced the unified spec tests (test_otel*.py, test/unified_format.py).
Green patch build across all supported server versions
Standard Evergreen builds for server logging

Checklist

Checklist for Author

Did you update the changelog (if necessary)? N/A
Is there test coverage?
Is any followup work tracked in a JIRA ticket? If so, add link(s). This will be combined with other tickets for OTel operation span support.

Checklist for Reviewer

Does the title of the PR reference a JIRA Ticket?
Do you fully understand the implementation? (Would you be comfortable explaining how this code works to someone else?)
Is all relevant documentation (README or docstring) updated?

Report db.operation.name for countDocuments, watch, renameCollection, collection-level bulkWrite, and both generic command helpers, per DRIVERS-3625. Use the same names in server selection logging, falling back to the command name for commands without a listed operation. Resync the OpenTelemetry and server selection logging spec tests, guard the client bulk_write span tests to servers with the bulkWrite command, and sweep the otel variant across all supported server versions.

Copilot

🟡 Changes recommended

It removes all server trace-context CI coverage and relies on a non-standard span attribute accessor.

2 open findings

Preserve OTel trace-context coverage in at least one CI variant · New
Track namespace initialization without relying on Span attributes · New

What changed in this PR

Aligns OpenTelemetry spans and server-selection logs with DRIVERS-3625 operation names.

Changes:

Normalizes operation names and namespaces across tracing and logging.
Adds synchronized operation-name fixtures and regression tests.
Expands OTel CI across supported server versions.

File	Description
`pymongo/_otel.py`	Updates operation-name and namespace handling.
`pymongo/operations.py`	Defines canonical operation names.
`pymongo/asynchronous/mongo_client.py`	Normalizes logged operations and propagates namespaces.
`pymongo/asynchronous/database.py`	Extracts generic-command collection names.
`pymongo/asynchronous/collection.py`	Names bulk, count, and rename operations.
`pymongo/asynchronous/change_stream.py`	Reports change streams as `watch`.
`pymongo/synchronous/mongo_client.py`	Synchronous generated counterpart.
`pymongo/synchronous/database.py`	Synchronous generated counterpart.
`pymongo/synchronous/collection.py`	Synchronous generated counterpart.
`pymongo/synchronous/change_stream.py`	Synchronous generated counterpart.
`test/asynchronous/unified_format.py`	Supports newly synchronized operations.
`test/asynchronous/test_otel.py`	Updates span expectations and version guards.
`test/asynchronous/test_otel_getmore.py`	Validates `watch` spans.
`test/unified_format.py`	Synchronous unified-runner counterpart.
`test/test_otel.py`	Synchronous OTel test counterpart.
`test/test_otel_getmore.py`	Synchronous change-stream counterpart.
`test/open_telemetry/operation/watch.json`	Adds `watch` tracing coverage.
`test/open_telemetry/operation/run_cursor_command.json`	Covers cursor command spans.
`test/open_telemetry/operation/run_command.json`	Covers generic command spans.
`test/open_telemetry/operation/rename_collection.json`	Covers rename spans.
`test/open_telemetry/operation/error_type.json`	Generalizes error-type matching.
`test/open_telemetry/operation/count_documents.json`	Covers `countDocuments` spans.
`test/open_telemetry/operation/collection_bulk_write.json`	Covers collection bulk-write naming.
`test/server_selection_logging/operation-names.json`	Adds operation-name logging coverage.
`test/server_selection_logging/operation-names-transactions.json`	Covers transactional operation names.
`test/server_selection_logging/standalone.json`	Updates expected log level.
`test/server_selection_logging/sharded.json`	Updates expected log level.
`test/server_selection_logging/replica-set.json`	Updates expected log level.
`test/server_selection_logging/operation-id.json`	Updates expected log levels.
`.evergreen/scripts/generate_config.py`	Expands the OTel version matrix.
`.evergreen/generated_configs/variants.yml`	Regenerates OTel CI tasks.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

…fix waiting-log level, avoid span attribute introspection

Copilot

🟡 Changes recommended

INFO-only server-selection logging is currently unreachable, and several companion-spec fixture cases are missing.

1 open finding

INFO server-selection logging never emits required WAITING message · New

2 resolved since last review

Track namespace initialization without relying on Span attributes
Preserve OTel trace-context coverage in at least one CI variant

Previously missed (2)

In code that hasn't changed since last review

Missing uniform delete case in collection bulk-write fixture

test/open_telemetry/operation/collection_bulk_write.json:440

This fixture is not fully resynced with the linked DRIVERS-3625 spec PR: the companion collection_bulk_write.json has a fourth case, uniform delete write models report delete, after this update case. Without it, the newly added DeleteOne/DeleteMany operation-name branch is never exercised as a uniform bulk.

Missing uniform update and delete bulk-write server-selection cases

test/server_selection_logging/operation-names.json:1234

The linked DRIVERS-3625 server-selection fixture includes uniform update and uniform delete collection bulk-write cases here, but this resync jumps directly from uniform insert to runCommand. Those omissions leave the new server-selection operation names for these two uniform bulk types unverified.

🧠 Review effort: Balanced

- Construct server selection telemetry for info-enabled logging so INFO users receive the WAITING message; add an INFO-only regression test - Match the OpenTelemetry Span API signatures in the test span stub and complete the _ConnectionTelemetryInfo protocol fields for mypy strict - Stop generating operation ids for info-only server selection logging; the spec makes operationId optional when the driver generates none - Re-sync the collection bulk write and logging fixtures with the spec

Copilot

🟡 Changes recommended

Remove the unused logging imports in both logger test modules.

3 open findings

Remove unused logging import · New
Remove unused logging import · New
INFO server-selection logging never emits required WAITING message

🧠 Review effort: Lite

Copilot

🔵 Needs a closer look

Fix async cursor command span metadata extraction so forwarded kwargs are represented correctly.

1 open finding

INFO server-selection logging never emits required WAITING message

2 resolved since last review

Remove unused logging import
Remove unused logging import

🧠 Review effort: Lite

Copilot

🔵 Needs a closer look

The broad cross-cutting telemetry changes span sync/async code, tests, and generated CI configuration, warranting final human review.

0 open findings

1 resolved since last review

INFO server-selection logging never emits required WAITING message

🧠 Review effort: Lite

blink1073 added 2 commits October 8, 2026 09:02

DRIVERS-3564: Build OpenSSL 3 for cryptography on s390x

34a2816

blink1073 requested a balanced review from Copilot October 8, 2026 22:28

blink1073 mentioned this pull request Oct 8, 2026

DRIVERS-3625 Document db.operation.name discrepancies and add missing covered operations mongodb/specifications#1993

Draft

4 tasks done

Copilot started reviewing on behalf of blink1073 October 8, 2026 22:28 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Comment thread .evergreen/scripts/generate_config.py

Comment thread pymongo/_otel.py Outdated

PYTHON-6054 address Copilot review: restore server trace-context CI, …

e50c757

…fix waiting-log level, avoid span attribute introspection

blink1073 requested a balanced review from Copilot October 9, 2026 00:28

Copilot started reviewing on behalf of blink1073 October 9, 2026 00:28 View session

Copilot AI reviewed Oct 9, 2026

View reviewed changes

Comment thread pymongo/_telemetry.py

blink1073 requested a lite review from Copilot October 9, 2026 01:53

Copilot started reviewing on behalf of blink1073 October 9, 2026 01:54 View session

Copilot AI reviewed Oct 9, 2026

View reviewed changes

Comment thread test/asynchronous/test_logger.py Outdated

Comment thread test/test_logger.py Outdated

remove unused logging import from logger tests

a56e901

blink1073 requested a lite review from Copilot October 9, 2026 02:17

Copilot started reviewing on behalf of blink1073 October 9, 2026 02:17 View session

Copilot AI reviewed Oct 9, 2026

View reviewed changes

blink1073 requested a lite review from Copilot October 9, 2026 10:28

blink1073 added this pull request to stack #3073 October 9, 2026 10:28

Copilot started reviewing on behalf of blink1073 October 9, 2026 10:28 View session

Copilot AI reviewed Oct 9, 2026

View reviewed changes

add authenticated replica set otel GitHub Actions variant

8d807ae

blink1073 closed this Oct 9, 2026

blink1073 reopened this Oct 9, 2026

Navigation Menu

Repository navigation

PYTHON-6054 Align span and log operation names with the OTel spec - #3111

PYTHON-6054 Align span and log operation names with the OTel spec#3111
blink1073 wants to merge 6 commits into
PYTHON-5855-traceparentfrom
PYTHON-6054-operation-names

blink1073 commented Oct 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

blink1073 commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes in this PR

Test Plan

Checklist

Checklist for Author

Checklist for Reviewer

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

blink1073 commented Oct 8, 2026 •

edited

Loading